

    \filetitle{matrix}{Insert matrix or numeric array}{report/matrix}

	\paragraph{Syntax}

\begin{verbatim}
P.matrix(Caption,Data,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{P} {[} struct {]} - Report object created by the
  \href{report/new}{\texttt{report.new}} function.
\item
  \texttt{Caption} {[} char \textbar{} cellstr {]} - Title or a cell
  array with title and subtitle displayed at the top of the matrix; see
  Description for splitting the title or subtitle into multiple lines.
\item
  \texttt{Data} {[} numeric {]} - Numeric array with input data.
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}arrayStretch=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1.15}} {]} - (Inheritable from parent
  objects) Stretch between lines in the matrix (in pts).
\item
  \texttt{\textquotesingle{}captionTypeface=\textquotesingle{}} {[}
  cellstr \textbar{} char \textbar{} *'\large\bfseries'* {]} - \LaTeX\\
  format commands for typesetting the matrix caption; the subcaption
  format can be entered as the second cell in a cell array.
\item
  \texttt{\textquotesingle{}colNames=\textquotesingle{}} {[} cellstr
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects) Names
  for individual matrix columns, displayed at the top of the matrix.
\item
  \texttt{\textquotesingle{}colWidth=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{NaN}} {]} - (Inheritable from parent objects)
  Width, or a vector of widhts, of the matrix columns in
  \texttt{em}units; \texttt{NaN} means the width of the column will
  adjust automatically.
\item
  \texttt{\textquotesingle{}condFormat=\textquotesingle{}} {[} struct
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects)
  Structure with .test and .format fields describing conditional
  formatting of individual matrix entries.
\item
  \texttt{\textquotesingle{}footnote=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - Footnote at the matrix title; only shows
  if the title is non-empty.
\item
  \texttt{\textquotesingle{}format=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{\textquotesingle{}\%.2f\textquotesingle{}}}
  {]} - (Inheritable from parent objects) Numeric format string; see
  help on the built-in \texttt{sprintf} function.
\item
  \texttt{\textquotesingle{}heading=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects)
  User-supplied heading, i.e.~an extra row or rows at the top of the
  matrix.
\item
  \texttt{\textquotesingle{}inf=\textquotesingle{}} {[} char \textbar{}
  \emph{\texttt{\textquotesingle{}\$\textbackslash{}infty\$\textquotesingle{}}}
  {]} - (Inheritable from parent objects) \LaTeX~string that will be
  used to typeset Infs.
\item
  \texttt{\textquotesingle{}long=\textquotesingle{}} {[} \texttt{true}
  \textbar{} \emph{\texttt{false}} {]} - (Inheritable from parent
  objects) If \texttt{true}, the matrix may stretch over more than one
  page.
\item
  \texttt{\textquotesingle{}longFoot=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects) Works
  only with \texttt{\textquotesingle{}long=\textquotesingle{}}
  \texttt{true}: Footnote that appears at the bottom of the matrix (if
  it is longer than one page) on each page except the last one.
\item
  \texttt{\textquotesingle{}longFootPosition=\textquotesingle{}} {[}
  \texttt{\textquotesingle{}centre\textquotesingle{}} \textbar{}
  \emph{\texttt{\textquotesingle{}left\textquotesingle{}}} \textbar{}
  \texttt{\textquotesingle{}right\textquotesingle{}} {]} - (Inheritable
  from parent objects) Works only with
  \texttt{\textquotesingle{}long=\textquotesingle{}} \texttt{true}:
  Horizontal alignment of the footnote in long matrices.
\item
  \texttt{\textquotesingle{}nan=\textquotesingle{}} {[} char \textbar{}
  \emph{\texttt{\textquotesingle{}\$\textbackslash{}cdots\$\textquotesingle{}}}
  {]} - (Inheritable from parent objects) \LaTeX~string that will be
  used to typeset \texttt{NaN}s.
\item
  \texttt{\textquotesingle{}pureZero=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects)
  \LaTeX~string that will be used to typeset pure zero entries; if empty
  the zeros will be printed using the current numeric format.
\item
  \texttt{\textquotesingle{}printedZero=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects)
  \LaTeX~string that will be used to typeset the entries that would
  appear as zero under the current numeric format used; if empty these
  numbers will be printed using the current numeric format.
\item
  \texttt{\textquotesingle{}rotateColNames=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} \textbar{} numeric {]}
  - Rotate the names of columns by the specified number of degrees;
  \texttt{true} means rotate by 90 degrees.
\item
  \texttt{\textquotesingle{}rowNames=\textquotesingle{}} {[} cellstr
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects) Names
  fr individual matrix rows, displayed left of the matrix.
\item
  \texttt{\textquotesingle{}separator=\textquotesingle{}} {[} char
  \textbar{}
  \emph{\texttt{\textquotesingle{}\textbackslash{}medskip\textbackslash{}par\textquotesingle{}}}
  {]} - (Inheritable from parent objects) \LaTeX~commands that will be
  inserted after the matrix.
\item
  \texttt{\textquotesingle{}sideways=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - (Inheritable from
  parent objects) Print the matrix rotated by 90 degrees.
\item
  \texttt{\textquotesingle{}tabcolsep=\textquotesingle{}} {[}
  \texttt{NaN} \textbar{} numeric {]} - (Inheritable from parent
  objects) Space between columns in the matrix, measured in em units;
  \texttt{NaN} means the \LaTeX~default.
\item
  \texttt{\textquotesingle{}typeface=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - (Not inheritable from parent objects)
  \LaTeX~code specifying the typeface for the matrix as a whole; it must
  use the declarative forms (such as \texttt{\textbackslash{}itshape})
  and not the command forms (such as
  \texttt{\textbackslash{}textit\{...\}}).
\end{itemize}

\paragraph{Generic options}

See help on \href{report/Contents}{generic options} in report objects.

\paragraph{Description}

\subparagraph{Conditional formatting}

The conditional format struct (or an array of structs) specified through
the \texttt{\textquotesingle{}condFormat=\textquotesingle{}} option must
have two fields, \texttt{.test} and \texttt{.format}.

The \texttt{.test} field is a text string with a Matlab expression. The
expression must evaluate to a scalar \texttt{true} or \texttt{false},
and can refer to the following attributes associated with each entry in
the data part of the matrix:

\begin{itemize}
\tightlist
\item
  \texttt{value} - the numerical value of the entry;
\item
  \texttt{row} - the row number within the data part of the matrix;
\item
  \texttt{col} - the column number within the data part of the matrix;
\item
  \texttt{rowname} - the row name right of which the entry appears;
\item
  \texttt{colname} - the column name under which the entry appears;
\item
  \texttt{rowvalues} - a row vector of all values in the current row;
\item
  \texttt{colvalues} - a column vector of all values in the current
  column;
\item
  \texttt{allvalues} - a matrix of all values.
\end{itemize}

You can combine a number of attribues within one test, using the logical
operators, e.g.

\begin{verbatim}
value > 0 && row > 3
value == max(rowvalues) && strcmp(rowname,'x')
\end{verbatim}

The \texttt{.format} fields of the conditional format structure consist
of LaTeX commands that will be use to typeset the corresponding entry.
The reference to the entry itself is through a question mark. The
entries are typeset in math mode; this for instance meanse that for bold
or italic typface, you must use the
\texttt{\textbackslash{}mathbf\{...\}} and
\texttt{\textbackslash{}mathit\{...\}} commands.

In addition to standard LaTeX commands, you can use the following IRIS
commands in the format strings:

\begin{itemize}
\tightlist
\item
  \texttt{\textbackslash{}sprintf\{FFFF\}} - to modify the way each
  numeric entry that passes the test is printed by the \texttt{sprintf}
  function; \texttt{FFFF} is one of the standard sprintf formattting
  strings.
\end{itemize}

You can combine multiple tests and their correponding formats in one
structure; they will be all applied to each entry in the specified
order.

\subparagraph{Titles and subtitles}

The input argument \texttt{Caption} can be either a text string, or a
1-by-2 cell array of strings. In the latter case, the first cell will be
printed as a title, and the second cell will be printed as a subtitle.

To split the title or subtitle into multiple lines, use the following
LaTeX commands wrapped in curly brackets:
\texttt{\{\textbackslash{}\textbackslash{}\}} or
\texttt{\{\textbackslash{}\textbackslash{}{[}Xpt{]}\}}, where \texttt{X}
is the width of an extra vertical space (in points) added between the
respective lines.

\paragraph{Example}


